home *** CD-ROM | disk | FTP | other *** search
/ Beginning Mac Programming / Beginning Mac Programming.bin / Open Me for REALbasic 3 / REALbasic 3.2 / Example Projects / Techniques / Examples by Thomas Tempelmann / TT's FileMgr-Plugin / FileMgr Plugin - ReadMe next >
Text File  |  1999-07-04  |  9KB  |  166 lines
  1. TT's FileMgr Plugin for REALbasic
  2.  
  3. General Information
  4.  
  5. By Thomas Tempelmann
  6. Current version: 1.2 (July 4, 1999)
  7.  
  8. This is freeware. Use it as you like.
  9. (And if you have created some nice things, think about sharing them, too!)
  10.  
  11. This is a Plugin for REALbasic. Plugins contain usually low-level code that cannot be written using the REALbasic language directly.
  12.  
  13. The plugin and the sample RB program were created and tested using CodeWarrior Pro 3 and REALbasic versions 1.1.1 and 2.0.2.
  14.  
  15. More REALbasic examples can be found on my Web Site at
  16.  
  17.   <http://www.tempel.org/rb>
  18.  
  19. Enjoy!
  20.  
  21.  
  22. Overview
  23.  
  24. This plugin gives you access to some functions of the Mac OS File Manager, such as relating RB's FolderItems to a Volume Reference Number (VRefNum), checking for Server volumes and getting more information about files (File Flags and Attributes).
  25.  
  26. One of the functions is particularly helpful: RB 1.1.1 (and before) crashes when you open and then again close the resource fork of a file that is already opened by another application or by the RB IDE. To prevent that, you can use IsResourceForkOpen before you open the resource fork and then do not close the resource fork again if it was open before.
  27.  
  28. Installation
  29.  
  30. 1. Quit REALbasic if it is running
  31.  
  32. 2. Place the file TT's FileMgr-Plugin into a folder called Plugins, that resides in the same folder where your REALbasic application is.
  33.  
  34. 3. Now you can launch REALbasic again and the methods described below will be available for your RB applications and the enclosed demo code.
  35.  
  36. Plugin Functions
  37.  
  38. • NewFolderItemFromFSSpec(fsSpec as MemoryBlock) as FolderItem
  39.  
  40. Creates a FolderItem from a FSSpec record, which must be passed in as a String of exactly 70 bytes in length (which means that LenB(fsSpec) must be equal to 70).
  41.  
  42. • NewFolderItem(vRefNum as Integer, parID as Integer, name as String) as FolderItem
  43.  
  44. Creates a FolderItem from a specified volume, the item's directory ID and its name.
  45.  
  46. • IsOnRemoteVolume(fileOrFolder as FolderItem) as Boolean
  47.  
  48. Returns true if the file or folder is located on a server volume.
  49.  
  50. • VolGetVRefNum(fileOrFolder as FolderItem) as Integer
  51.  
  52. Returns the volume reference number (vRefNum) of any file or folder. Those vRefNums are unique to a mounted volume. For example, to find out if two files are on the same volume, check if their vRefNums are equal.
  53.  
  54. • VolumeByVRefNum(vRefNum as Integer) as FolderItem
  55.  
  56. Pass in the vRefNum of any mounted volume and it returns the Volume as a FolderItem.
  57. Returns nil if the vRefNum was invalid.
  58.  
  59. • GetFileFlags(file as FolderItem) as Integer
  60.  
  61. Returns the fdFlags of a file. If you pass in a non-existing file or a folder, a negative error code is returned instead.
  62. The fdFlags is a set of bits with the following meaning:
  63.     • bit 15, value &H8000: isAlias
  64.     • bit 14, value &H4000: isInvisible
  65.     • bit 13, value &H2000: hasBundle (has a BNDL resource)
  66.     • bit 12, value &H1000: nameLocked
  67.     • bit 11, value &H0800: isStationary
  68.     • bit 10, value &H0400: hasCustomIcon
  69.     • bit 8, value &H0100: hasBeenInited (Finder has seen the file since it has been created)
  70.     • bit 7, value &H0080: hasNoINITs (there's no INIT rsrc in the Extension file)
  71.     • bit 6, value &H0040: isShared
  72.     • bits 1-3, value &H000E: color (as a 3-bit value from 0-7)
  73. For example, testing for a file being invible works like this:
  74.     fdFlags = GetFileFlags(f)
  75.     if fdFlags < 0 then
  76.          ... oops, an error occured
  77.     else
  78.         fileIsInvisible = BitwiseAnd (fdFlags, &H4000) <> 0
  79.         // or:
  80.         fileIsInvisible = IsBitSet (fdFlags, 14)
  81.     end
  82.  
  83. • SetFileFlags(file as FolderItem, flags as Integer) as Integer
  84.  
  85. Sets the fdFlags of a file. Returns an error code (or zero if no error occured). Possible error conditions include "disk is write protected" and "file not found".
  86. When changing flags of a file, use GetFileFlags to get the original flags, then clear or set the flags by using BitwiseAnd and BitwiseOr and call SetFileFlags to set the new flags.
  87.  
  88. For example, clearing a file's hasCustomIcon flag works like this:
  89.     fdFlags = GetFileFlags(f)
  90.     if fdFlags >= 0 then
  91.         err = GetFileFlags(f, BitSet(fdFlags, 10, false))
  92.         if err <> 0 then
  93.             ... oops, an error occured (for instance, the disk could be write protected)
  94.         end
  95.     end
  96.  
  97. • GetFolderFlags(folder as FolderItem) as Integer
  98.  
  99. Returns the frFlags of a folder. If you pass in a non-existing folder, a negative error code is returned instead.
  100. The frFlags are similar to the fdFlags (see GetFileFlags), but only a subset of them is used with folders.
  101.  
  102. • SetFolderFlags(folder as FolderItem, flags as Integer) as Integer
  103.  
  104. Sets the frFlags of a folder. Returns an error code (or zero if no error occured). Possible error conditions include "disk is write protected" and "folder not found".
  105. When changing flags of a folder, use GetFolderFlags to get the original flags, then clear or set the flags by using BitwiseAnd and BitwiseOr and call SetFolderFlags to set the new flags.
  106.  
  107. • GetFileAttribute(file as FolderItem) as Integer
  108.  
  109. Returns the flAttrib of a file. If you pass in a non-existing file or a folder, a negative error code is returned instead.
  110. The flAttrib is a set of bits with the following meaning:
  111.     • bit 0, value 1: file is locked
  112.     • bit 2, value 4: resource fork is open
  113.     • bit 3, value 8: data fork is open
  114.     • bit 4, value 16: item is a directory
  115.     • bit 7, value 128: file (one or both forks) is open
  116. (See GetFileFlags for an example on how to check the bits)
  117.  
  118. • IsFileOpen(file as FolderItem) as Boolean
  119.  
  120. Returns true if the item is a file and that file is open (in use). Equivalent to calling GetFileAttribute and testing bit 7.
  121.  
  122. • IsResourceForkOpen(file as FolderItem) as Boolean
  123.  
  124. Returns true if the item is a file and that its resource fork is open (in use). Equivalent to calling GetFileAttribute and testing bit 2.
  125.  
  126. • VolGetFolderItemID(item as FolderItem, createFileIDs as Boolean) as Integer
  127.  
  128. Returns the unique FileID or DirID of a FolderItem. This ID is unique over all items on the same volume. The value 2 always identifies the root directory, all negative values and positive ones above 15 are used for user-created files and folders, while the values 3-15 are used internally by the File System (for the Desktop Database, for example).
  129. If the item does not exists, 0 (zero) is returned instead.
  130.  
  131. IDs for Folders can always be resolved back to a FolderItem using VolResolveID, while resolving FileIDs only works when they've previously been created explicitly. To create a resolvable FileID, pass true to the createFileIDs parameter. But be aware that if the FileID can not be created (because the disk is locked or because the File System Format does not support it), the call will fail and a zero will be returned!
  132. So, if you are just interested in reading the FileID, pass false to the second parameter. This will not fail even there hasn't been created a resolvable ID for that file yet.
  133.  
  134. • VolResolveID(vRefNum as Integer, id as Integer) as FolderItem
  135. • VolResolveID(vol as FolderItem, id as Integer) as FolderItem
  136.  
  137. Both functions return a FolderItem for a passed FileID or DirID. If the item can not be resolved, nil is returned instead.
  138. The first parameter specified the volume where you want to resolve the ID on.
  139.  
  140.  
  141. Programming Information
  142.  
  143. The plugin code is a Metrowerks CodeWarrior Pro 3 (IDE 3.1) project.
  144. If you have an older CW version that refuses to open the prj file, then create a new and set/enable the following prj options:
  145. • create 68K target (set to 68K linker)
  146. • prj type: Code Resource, File Name "CatalogSearch-Plugin", Creator "SfTg", Type "RBPl", ResType "PL68", ResID "128", Extended Resource, Header Type "Standard"
  147. • C/C++ language settings: Prefix File "MacHeaders.h"
  148. • 68K Processor: 68020 Codegen, Code Model "Smart", Struct Alignm. "PowerPC", 4-Byte Ints, 8-Byte Doubles, MPW C Call. Conv.
  149. • 68K Linker: Link Single Segment, Merge Compiler Glue…, Dead-strip Static Init Code
  150. • Add the files "Plugin Source.cpp", "PluginMain.cpp", "MacOS.lib", "Version Info.rsrc" and a 68K C lib with "(4i_8d)" and "A4" in its name to the project.
  151.  
  152. To compile the project, you also need to have the "Plugin SDK" available, which you can download from RB's website.
  153.  
  154.  
  155. Revision history
  156.  
  157. 8 Mar 99, v1.0:
  158.     First release.
  159.  
  160. 26 March 99, v1.1
  161.     Added the functions SetFileFlags, Set/GetFolderFlags, VolGetFolderItemID and VolResolveID.
  162.     Added the module BitwiseTools to the sample project that provides functions to check and set the bits of an Integer.
  163.  
  164. 4 July 99, v1.2
  165.     Added two routines to create a FolderItem from Mac OS file/folder specs (NewFolderItem...).
  166.